Netvend Server
Summary The netvend server expects a request containing a public address, a command, and a cryptographic signature of the command. First, the server verifies that the signature corresponds to the correct address, and that the address has netvend credit. If the request fails either of these tests, the server immediately sends back an error code and halts any processing. Assuming the signature was legitimate, and the account has credit, the server deducts the appropriate fee, processes the command, and sends back a response. All commands are stored transparently with their signature within the 'history' table, which is accessible to any agent via the Query command. Structure of a netvend request The netvend server expects 3 variables (address, command, signed) included as POST, GET, or other REQUEST variables. 'address' is simply the plaintext address of the agent that is being used to carry out the command. 'command' is a json-encoded string, detailed in the 'command structure and pathing' section below. 'signed' is a cryptographic signature generated from the private key corresponding to 'address' and the string 'command' (after it has been json-encoded). Command Structure and Pathing It may be helpful to use the netvend command page, to see exactly how commands are handled. 'command' is a json-encoded string representing an array: command0 indicates the type of command. 'p' for post, 't' for tip, 'q' for query, or 'w' for withdraw. Post commands expect command1 to hold the post itself. At the moment, the post must be less than 65kb, as this is the max field size in the SQL posts table. Tip commands expect 3 additional arguments: command1 = address of the recipient, command2 = amount of tip (in uSats), and command3 = referenced post id (0 can be used to indicate none). Query commands expect 2 additional arguments: command1 = the SELECT query itself, and command2 is the maximum allowable query cost (in uSats). If the cost of the query ends up exceeding this value, the information won't be returned. The agent will still be charged, however. Withdraw commands expect only one more additional argument: command1 = amount (in uSats). Netvend Response Structure Netvend returns an array, which we'll call response. response0 is a bool representing the command's success. If success 0: response1 = error code, a single character indicating the type of error encountered. See the command.php page for more info. response2 contains more specific information. For example, if it doesn't recognize the given signature as valid, it will return the command and signature it received; or if the agent didn't have enough funds, it will return the account balance and command cost. If success 1: response1 = history_id, the id of the row in the history table corresponding to the processed command. response2 = the amount (in uSats) it cost to perform the command (this does not count any tips sent--only the fee of sending the tips) response3 = command_result, which changes based on which command was used: For Post and Tip, command_result contains the id of the new post or tip. For Query, command_result contains a dictionary that holds success, num_rows, and rows. For Withdraw, command_result simply contains a 1 for success.